home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.093 < prev    next >
Encoding:
Text File  |  1990-09-21  |  10.7 KB  |  225 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #93:    Compatible Printing
  8.  
  9. Written by:    Matt Deatherage    September 1990
  10.  
  11. This Technical Note discusses printing on the Apple IIgs and how you can make 
  12. your printing code more compatible.
  13. _____________________________________________________________________________
  14.  
  15.  
  16. How Does Printing Work Anyway?
  17.  
  18. There are, in general, two types of printing done on the Apple IIgs.  The 
  19. first kind is "desktop" printing, which uses the Apple IIgs Print Manager to 
  20. render images created by QuickDraw II onto an output device.  The other kind 
  21. of printing is "text" printing, which is similar to the way classic Apple II 
  22. applications print--you send ASCII text somewhere and a printer prints it as 
  23. ASCII text.  This printing normally involves no graphics and is very quick.
  24.  
  25. This Note covers both types of printing, and by understanding the internals 
  26. and the methods used to print, you can avoid compatibility headaches in the 
  27. future.
  28.  
  29.  
  30. Desktop Printing
  31.  
  32. Desktop printing uses the Apple IIgs Print Manager.  The process is described 
  33. in detail in the Print Manager chapter of the Apple IIgs Toolbox Reference, 
  34. and usually consists of a simple print loop:
  35.  
  36.     Open a document (PrOpenDoc)
  37.         Open a page (PrOpenPage)
  38.         Draw or Image the page in your favorite way
  39.         Close the page (PrClosePage)
  40.         Repeat for each page
  41.     Close the document (PrCloseDoc)
  42.     Print the document if it's spooled (PrPicFile)
  43.  
  44. Note that you should always call PrPicFile at the end of your print loop.  It 
  45. completes the printing process, even for immediate or draft printing.
  46.  
  47. There's one real secret about the Print Manager that can cloud your 
  48. understanding of printing--the Print Manager doesn't actually do anything.  It 
  49. loads, unloads, and keeps track of printer drivers and port drivers and 
  50. performs some necessary housekeeping, but that's about it.  Many people 
  51. believe that the Print Manager is responsible for all imaging, managing 
  52. documents, managing a printing grafPort and such, but it's not.  (The myth is 
  53. perpetuated by the Toolbox Reference which refers to these functions as 
  54. handled by the Print Manager.)  In fact, these functions are handled by 
  55. printer drivers.
  56.  
  57. You actually call the printer driver for all of the routines in the print 
  58. loop; all the Print Manager does is make sure the driver is loaded and 
  59. dispatch to it.  Therefore, most of the compatibility issues you have with 
  60. printing are not with the Print Manager, but with printer drivers.
  61.  
  62. Dealing With the Print Record
  63.  
  64. It's the printer driver's job to get information about a printing job from the 
  65. user (it's the printer driver that handles the style and job dialog boxes, 
  66. since the Print Manager cannot generically know what style and job options any 
  67. printer can support), keep track of it, and print the document using those 
  68. settings.  Those settings are kept in a data structure associated with a 
  69. document known as a print record.
  70.  
  71. Apple had only released two printer drivers at the time the first volume of 
  72. the Toolbox Reference was published, and therefore the descriptions of the 
  73. print record in that volume tend to be absolute.  For example, the iDev field 
  74. is documented as "one for an ImageWriter and three for a LaserWriter."  In 
  75. fact, the iDev field is the only method of print record interpretation 
  76. available and there are several values for it:
  77.  
  78.     $0001 = ImageWriter
  79.     $0002 = ImageWriter LQ
  80.     $0003 = LaserWriter
  81.     $0004 = Epson
  82.     $8001 = Generic dot-matrix (interprets the style subrecord like the 
  83.             ImageWriter driver)
  84.     $8003 = Generic laser printer (interprets the style subrecord like the 
  85.             LaserWriter driver)
  86.  
  87. If you have checks in your code like "If it's not $0001, it must be a 
  88. LaserWriter," you have problems with most of the other printer types.
  89.  
  90. The $8000 and greater iDev values are defined for third-party printer drivers.  
  91. The printer driver has no way other than the print record to keep track of 
  92. values for a given print job, so it has to store all such information in the 
  93. print record.  If all third-party drivers use proprietary style subrecord 
  94. formats, no applications can read or set any of those values.  Those drivers 
  95. which can use the compatible $8000 and greater iDev values indicate to 
  96. applications that the definitions in Toolbox Reference for the ImageWriter and 
  97. LaserWriter drivers apply to these drivers as well.  iDev values of $0002 or 
  98. $0004 also interpret the style subrecord as the ImageWriter driver does.
  99.  
  100. Print Record Rules
  101.  
  102. Remember:  the print record is the only way the printer driver has to maintain 
  103. information about a particular job.  The print record belongs to the user, the 
  104. document, and the printer driver--not the application.  Here are some rules for 
  105. staying out of print record trouble.
  106.  
  107.   o  Always call PrValidate when changing fields in the print record.  
  108.      Even if a driver interprets the style subrecord like the 
  109.      ImageWriter driver, it may not support all the ImageWriter's style 
  110.      features (e.g., color printing).  Calling PrValidate every time 
  111.      you change something in the print record gives the printer driver 
  112.      a chance to look at the havoc you've wreaked and correct it if 
  113.      necessary.
  114.  
  115.      You do not always get a feature you want.  If a printer does not 
  116.      support color printing, you can set the "color" bit all day long 
  117.      and PrValidate clears it every time.  You should be prepared for a 
  118.      new printer driver that does not support the features you want, 
  119.      and inform the user that the feature is not supported by this 
  120.      printer.
  121.  
  122.   o  Do not patch PrValidate to make it ignore bogus values in the 
  123.      print record unless instructed to do so by the printer driver 
  124.      author.
  125.  
  126.   o  Never, never tread on reserved fields in the print record.  If you 
  127.      find a particular driver storing useful values some place, forget 
  128.      it.  This is the only place a driver has to store information 
  129.      about a print job and some of it is not going to be supported.
  130.  
  131.      In particular, never try to interpret any values you may find in 
  132.      the printX subrecord of the print record.  This subrecord is for 
  133.      the private use of printer drivers.  Although printX is currently 
  134.      the worst compatibility risk, you must not tamper with other 
  135.      reserved fields.
  136.  
  137.   o  If you want to learn more about printing, learn how printer 
  138.      drivers work.  The specifications are in Apple IIgs Technical Note 
  139.      #35, appropriately entitled "Printer Driver Specifications."  An 
  140.      understanding of how printer drivers do their work is an 
  141.      understanding of how printing works.
  142.  
  143.  
  144. Text Printing
  145.  
  146. Text printing generally uses the built-in ASCII mode of most dot-matrix 
  147. printers to print text quickly and efficiently.
  148.  
  149. Desktop printer drivers often have a "draft" mode, where they print text 
  150. immediately instead of imaging it in the appropriate font and style.  This is 
  151. accomplished by intercepting low-level QuickDraw II routines called bottleneck 
  152. procedures.  When QuickDraw is called to draw text, the printer driver gets 
  153. control instead and sends the text to the printer.
  154.  
  155. Although this is useful to users of desktop printer drivers, it is not a 
  156. required feature of any printer driver, and those that do implement it each do 
  157. so in their individual way.  For example, the LaserWriter driver doesn't 
  158. support this model of "draft" printing because the LaserWriter is normally a 
  159. PostScript(R) device--sending straight ASCII to it doesn't necessarily work.
  160.  
  161. To imitate the way classic Apple II applications print, your application 
  162. prompts the user for some device through which to print, and ASCII characters 
  163. are sent through that device.  There are a few ways to do this.
  164.  
  165. Using the Print Manager
  166.  
  167. You can still use the Print Manager to print in ASCII mode by bypassing the 
  168. printer driver.  Simply use the Port Driver to send ASCII characters to the 
  169. given target device with the PrDevWrite call.  The specifications for Port 
  170. Driver calls are in Apple IIgs Technical Note #36, also appropriately entitled 
  171. "Port Driver Specifications."  You make port driver calls as if they were 
  172. Print Manager calls.
  173.  
  174. Although this method has been used, Apple does not recommend it.  If the 
  175. selected port driver is a network driver, this method is troublesome.
  176.  
  177. Using the Text Tools
  178.  
  179. By using the Apple IIgs Text Tools, you can ask the user what slot to print 
  180. through and send ASCII characters to that slot or port.  Although this is 
  181. better than using the Port Driver, it still has problems.  The Text Tools 
  182. cannot be fully GS/OS Slot Arbiter compatible; therefore, there might be GS/OS 
  183. devices accessible to the user to which your application does not let him 
  184. print.  Also, it's difficult to detect which slots really have Text Tools' 
  185. devices without knowing about Apple II firmware, and prompting the user for a 
  186. slot number invites trying to print to the disk firwmare, which usually justs 
  187. reboot the machine (unceremoniously).
  188.  
  189. Using GS/OS
  190.  
  191. GS/OS supports character drivers, such as printer interfaces, and using them 
  192. is the best way to handle ASCII printing.  GS/OS supports loaded drivers for 
  193. character devices if you have them, and generates drivers for character 
  194. devices it can recognize.  In addition, GS/OS drivers have identification 
  195. words so you can prompt with real messages instead of cryptic slot numbers.
  196.  
  197. You can use the GS/OS call DInfo to loop through all drivers and prepare a 
  198. list of character drivers.  You can then change their device IDs into text 
  199. phrases, place them in a list, and prompt the user to select one.  This call 
  200. usually results in a list such as "Printer port, Modem port, Remote Print 
  201. Manager, Printer interface, Text screen [the Console driver]."  You may wish 
  202. to change the names of the devices slightly to make the choice easier (e.g., 
  203. "network printer" instead of "Remote Print Manager").
  204.  
  205. Apple strongly recommends using GS/OS for ASCII printing from 16-bit 
  206. applications.
  207.  
  208. Note:  The Remote Print Manager (.RPM) device driver in System Software 
  209.        5.0 to 5.0.2 has a bug which causes character loss.  System 
  210.        Software 5.0.3 fixes this bug.
  211.  
  212.  
  213. Further Reference
  214. _____________________________________________________________________________
  215.   o  Apple IIgs Toolbox Reference
  216.   o  GS/OS Reference
  217.   o  Apple IIgs Technical Note #34, Low-level QuickDraw II Routines
  218.   o  Apple IIgs Technical Note #35, Printer Driver Specifications
  219.   o  Apple IIgs Technical Note #36, Port Driver Specifications
  220.   o  Apple IIgs Technical Note #69, The Ins and Outs of Slot Arbitration
  221.   o  Apple IIgs Technical Note #75, BeginUpdate Anomaly
  222.  
  223. PostScript is a registered trademark of Adobe Systems Incorporated.
  224.  
  225.